---
title: 핸드오프
description: Delegate tasks from one agent to another
---

import { Code } from '@astrojs/starlight/components';
import basicUsageExample from '../../../../../../examples/docs/handoffs/basicUsage.ts?raw';
import customizeHandoffExample from '../../../../../../examples/docs/handoffs/customizeHandoff.ts?raw';
import handoffInputExample from '../../../../../../examples/docs/handoffs/handoffInput.ts?raw';
import inputFilterExample from '../../../../../../examples/docs/handoffs/inputFilter.ts?raw';
import recommendedPromptExample from '../../../../../../examples/docs/handoffs/recommendedPrompt.ts?raw';

핸드오프는 에이전트가 대화의 일부를 다른 에이전트에 위임할 수 있게 합니다. 이는 서로 다른 에이전트가 특정 분야에 특화되어 있을 때 유용합니다. 예를 들어 고객 지원 앱에서는 예약, 환불 또는 FAQ를 처리하는 에이전트를 둘 수 있습니다.

핸드오프는 LLM에게 도구로 표현됩니다. `Refund Agent`라는 에이전트로 핸드오프하면 도구 이름은 `transfer_to_refund_agent`가 됩니다.

## 핸드오프 생성

모든 에이전트는 `handoffs` 옵션을 허용합니다. 여기에 다른 `Agent` 인스턴스나 `handoff()` 헬퍼가 반환하는 `Handoff` 객체를 포함할 수 있습니다.

### 기본 사용

<Code lang="typescript" code={basicUsageExample} title="Basic handoffs" />

### `handoff()`를 통한 핸드오프 사용자 지정

`handoff()` 함수는 생성되는 도구를 튜닝할 수 있게 해줍니다.

- `agent` – 핸드오프할 대상 에이전트
- `toolNameOverride` – 기본 `transfer_to_<agent_name>` 도구 이름 재정의
- `toolDescriptionOverride` – 기본 도구 설명 재정의
- `onHandoff` – 핸드오프가 발생할 때 호출되는 콜백. `RunContext`와 선택적으로 파싱된 입력을 전달받음
- `inputType` – 핸드오프에 기대되는 입력 스키마
- `inputFilter` – 다음 에이전트에 전달할 히스토리 필터

<Code
  lang="typescript"
  code={customizeHandoffExample}
  title="Customized handoffs"
/>

## 핸드오프 입력

가끔은 핸드오프를 호출할 때 LLM이 데이터를 제공하길 원할 수 있습니다. 입력 스키마를 정의하고 `handoff()`에서 사용하세요.

<Code lang="typescript" code={handoffInputExample} title="Handoff inputs" />

## 입력 필터

기본적으로 핸드오프는 전체 대화 히스토리를 전달받습니다. 다음 에이전트에 무엇을 넘길지 변경하려면 `inputFilter`를 제공하세요.
공통 헬퍼는 `@openai/agents-core/extensions`에 있습니다.

<Code lang="typescript" code={inputFilterExample} title="Input filters" />

## 권장 프롬프트

프롬프트에 핸드오프를 언급하면 LLM이 더 안정적으로 반응합니다. SDK는 `RECOMMENDED_PROMPT_PREFIX`를 통해 권장 접두어를 제공합니다.

<Code
  lang="typescript"
  code={recommendedPromptExample}
  title="Recommended prompts"
/>
